From 3afd5d7a892cedd4d48e9c88e7864e2ca1cb647d Mon Sep 17 00:00:00 2001
From: Matthias Clasen <mclasen@redhat.com>
Date: Thu, 29 Oct 2020 13:57:22 -0400
Subject: [PATCH] docs: Tweak GdkSurface docs

Add more details, and refer to the GdkToplevel / GdkPopup
docs.
---
 gdk/gdksurface.c | 11 +++++++++--
 1 file changed, 9 insertions(+), 2 deletions(-)

diff --git a/gdk/gdksurface.c b/gdk/gdksurface.c
index c32c17262b..43d3371609 100644
--- a/gdk/gdksurface.c
+++ b/gdk/gdksurface.c
@@ -55,10 +55,17 @@
  * SECTION:gdksurface
  * @Short_description: Onscreen display areas in the target window system
  * @Title: Surfaces
+ * @See_also: #GdkToplevel, #GdkPopup
  *
  * A #GdkSurface is a (usually) rectangular region on the screen.
- * It’s a low-level object, used to implement high-level objects such as
- * #GtkWindow on the GTK level.
+ * It’s a low-level object, used to implement high-level objects
+ * such as #GtkWindow or #GtkDialog in GTK.
+ *
+ * The surfaces you see in practice are either #GdkToplevel or
+ * #GdkPopup, and those interfaces provide much of the required
+ * API to interact with these surfaces. Other, more specialized
+ * surface types exist, but you will rarely interact with them
+ * directly.
  */
 
 /**
-- 
2.30.2